<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="en">
<head>
<meta name="copyright" content="Copyright (c) 2016, 2017 IBM Corporation and others. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
<title>Incompatibilities between Eclipse 4.6 and 4.7</title>
</head>

<body>

<h1>Incompatibilities between Eclipse 4.6 and 4.7</h1>

<p>
  Eclipse changed in incompatible ways between 4.6 and 4.7 in ways that affect
  plug-ins. The following entries describe the areas that changed and provide
  instructions for migrating 4.6 plug-ins to 4.7. Note that you only need to look
  here if you are experiencing problems running your 4.6 plug-in on 4.7.
</p>
<p>
See also the list of <a href="../removals.html">deprecated API removals</a> for this release.
</p>

<ol>
<li><a href="#progress-convention">New calling convention for progress monitors</a></li>
</ol>

<hr>

<!-- ############################################## -->
<h2><a name="progress-convention">1. New calling convention for progress monitors</a></h2>

<p><strong>What is affected:</strong>
<p>All methods which obtain their own top-level IProgressMonitor.</p>

<p><strong>Description:</strong>
<p>
In order to reduce boilerplate code, Eclipse 4.7 has introduced a new calling convention for
methods which receive an <code>org.eclipse.core.runtime.IProgressMonitor</code> as a parameter. In Eclipse 4.7 it is the
caller's responsibility to invoke <code>done()</code> on IProgressMonitor rather than the
receiver's. Callers can choose to use SubMonitor, which doesn't require the use of
<code>done()</code>. This means that &mdash; in practice &mdash; most
invocations of <code>done()</code> will be deleted along with their surrounding try/catch blocks.
<p>
This is not a breaking change for methods which receive a progress monitor as an argument, since
they can tolerate callers whether or not the caller invokes done(). However, it may be a breaking
change for methods that obtain their own top-level progress monitors.
<p>
Methods which obtain their own top-level progress monitors rather than receiving one as a
parameter are now responsible for invoking done() on those monitors. Technically, they were
always responsible for doing this, but some of them didn't do so because any method they
passed it to would have invoked done() on their behalf. Now this will matter and the methods
will need to be changed. For example:

<pre>
// Before:
public void doSaveAs() {
  IProgressMonitor monitor= getProgressMonitor();
  performSaveAs(monitor);
}
</pre>

<pre>
// After:
public void doSaveAs() {
  IProgressMonitor monitor= getProgressMonitor();
    try {
      performSaveAs(monitor);
    } finally {
      monitor.done();
    }
}
</pre>

<p>
Fortunately there are few of these methods and they are easy to find.
<p>
<strong>Action required:</strong>
<ul>
<li>Open the Call Hierarchy on <code>StatusLineManager#getProgressMonitor()</code>.</li>
<li>Ensure that all callers of these methods contain a finally block that
    invokes done (as in the doSaveAs() example, above).</li>
<li>Open the Type Hierarchy of <code>IProgressMonitor</code>. Look for progress monitors which do something in
    their done() method besides reporting work, setting a task name, or calling done on another
    monitor. SubMonitor can be ignored. Monitors which set a control's visibility or deallocate a
    resource in their done() method must not be ignored.</li>
<li>Use the Call Hierarchy view to locate every place that instantiates or accesses an instance of
    one of those classes. Ensure that those access points contain a try/finally block that invokes done().</li>
</ul>

<p><strong>More Information:</strong>
<p>
See <a href="https://eclipse.org/articles/Article-Progress-Monitors/article.html" target="_blank">this article</a> for
more examples of how to use progress monitors with the new calling convention. Background and discussion
about this change <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=487372" target="_blank">can be found here.</a>


<!-- ############################################## -->

<h2>2. <a name="bidi-1.0.0">javax.xml removed from org.eclipse.e4.rcp feature</a></h2>
<p><strong>What is affected:</strong> Clients that refer to
the <code>javax.xml</code> bundle and use the <code>org.eclipse.e4.rcp</code> feature for that dependency.
</p>
<p><strong>Description:</strong>

The <code>javax.xml</code> plug-in has been removed from the <code>org.eclipse.e4.rcp</code> feature.
The <code>javax.xml</code> package is provided by JavaSE 1.7 and the Eclipse Platform requires Java 1.8.
</p>
If you have a dependency to this bundle and if you are using the
org.eclipse.e4.rcp you need to adjust require-bundle: javax.xml to
import-package in the corresponding MANIFEST.MF.

</body>
</html>
